feat: expose narrow setters on EventSource for RETRY-spec regime switching - #109

Summary

Adds two narrow public setter methods on EventSource — setInitialRetryDelayMillis(long) and setMaxRetryDelayMillis(long) — for SDK-driven regime switching. The motivating use case is RETRY-spec conformance in server SDKs: on classification of a failure as "unexpected" (per RETRY §1.6 / §1.7), the SDK's data source shifts retry timing into an extended regime (e.g., initial 5 min, max 1 hr), and shifts back after healthy operation.

• Tracked as SDK-2789 under the RETRY-conformance epic SDK-2775.
• Cross-referenced by server-sdk-guide.md — the cross-cutting implementation guide feeding forward from the Go reference implementation (SDK-2788).
• Implementation plan at SDK-2789 plan.md (§4.1 covers the API-shape decision, §4.5 covers the cross-repo sequencing).

What ships

Two public methods on EventSource:

• setInitialRetryDelayMillis(long millis) — updates the existing volatile baseRetryDelayMillis field (same field the wire-side SetRetryDelayEvent already updates); if the current strategy is a DefaultRetryDelayStrategy, the exponent counter is reset so the first subsequent apply() uses the new base directly.
• setMaxRetryDelayMillis(long millis) — constructs a new immutable DefaultRetryDelayStrategy with the specified max delay and the exponent counter reset to 0, preserving the current backoff multiplier and jitter multiplier, and atomically swaps the reference. No-op for custom strategy impls (which don't expose a max-delay concept via the abstract interface).

Both realize the "reset n when delays change" invariant from the LaunchDarkly server-SDK implementation guide: the first attempt in a new regime uses the new initial delay directly rather than newBase × 2^oldN.

Two package-private helpers on DefaultRetryDelayStrategy: withResetCounter() and withMaxDelayMillisAndResetCounter(long). Existing public builder methods (maxDelay, backoffMultiplier, jitterMultiplier) are unchanged.

currentRetryDelayStrategy field made volatile to support the "caller can invoke setters from any thread" contract.

Design notes

Alternative considered: expose a single setRetryDelayStrategy(RetryDelayStrategy) method that lets the caller replace the whole strategy. Rejected because it gives consumers too much rope — an SDK doing regime switching only needs to move min/max between regimes; it shouldn't be able to accidentally change jitter or backoff-multiplier as part of the same knob. The narrow-setter API keeps the public surface minimal.

The EventSource.baseRetryDelayMillis handling of server-directed retry: hints is orthogonal to the new setters and remains unchanged. A later wire hint continues to overwrite the SDK-set base delay, matching WHATWG HTML Living Standard EventSource semantics.

Testing

• 6 new unit tests in EventSourceRetryDelayStrategyUsageTest:
  • setInitialRetryDelayMillisUpdatesGetBaseRetryDelayMillis
  • setInitialRetryDelayMillisResetsExponentCounter
  • setMaxRetryDelayMillisClampsAndResetsExponentCounter
  • setInitialAndSetMaxComposeForExtendedRegimeSequence (asserts the RETRY spec's extended-regime doubling shape at ms-scale for test speed)
  • wireRetryHintStillTakesEffectAfterSdkSideSetters
  • settersOnCustomRetryDelayStrategyDoNotThrow
• Full unit suite: BUILD SUCCESSFUL, 0 failures.
• make contract-tests (sse-contract-tests harness): "All tests passed" end-to-end.

Test plan for reviewers

• Confirm the "narrow setter" API shape is preferred over a whole-strategy setter.
• Confirm currentRetryDelayStrategy being volatile is acceptable (the field was previously non-volatile with a comment noting it should only be accessed from the reading thread; the setters lift that invariant, and the volatile write is a defensive publication guarantee).
• Confirm the two new package-private helpers on DefaultRetryDelayStrategy are appropriately scoped.
• Sanity-check the wire-hint interaction test (wireRetryHintStillTakesEffectAfterSdkSideSetters) — the wire hint continues to override the SDK's initial delay after both setters have been used, which is intentional (SDK regime state ≠ wire-authoritative reconnect time).

Downstream

Consumed by java-server-sdk PR (SDK-2789) — Java SDK's RETRY-conformance work. That PR's CI will be red until this PR ships to Maven Central.